# 스트리밍 오류

스트리밍 오류란 LLM(Large Language Model)이 응답을 생성하여 클라이언트로 전송하는 과정에서 네트워크 단절, 타임아웃, 서버 과부하 등으로 인해 응답이 중단되거나 정상적으로 전달되지 않는 현상을 말한다.

## 1. 주요 원인

### 1.1 네트워크 불안정성
클라이언트와 서버 간의 연결이 불안정하거나, 중간 프록시 서버 및 게이트웨이에서 연결을 강제로 종료할 때 발생한다. 특히 HTTP 스트리밍(Server-Sent Events 등) 연결이 장시간 유지되어야 하는 특성상 네트워크 변동성에 취약하다.

### 1.2 서버 측 타임아웃
모델의 추론 시간이 설정된 타임아웃 임계값을 초과하거나, 서버 내부의 리소스 부족으로 인해 응답 생성이 지연되어 연결이 끊어지는 경우이다.

### 1.3 토큰 제한 및 생성 중단
최대 토큰 제한(Max Tokens)에 도달하여 생성이 강제로 종료되거나, 모델 내부의 안전 필터(Safety Filter) 작동으로 인해 생성 도중 응답이 중단되는 현상이 발생한다.

## 2. 신뢰성 강화 방안 (해결책)

### 2.1 재시도 전략 (Retry Logic)
일시적인 네트워크 오류나 서버 과부하를 해결하기 위해 재시도 로직을 구현한다.
- **지수 백오프(Exponential Backoff):** 재시도 간격을 점진적으로 늘려 서버의 부하를 줄이고 복구 시간을 확보하는 알고리즘을 적용한다.
- **최대 재시도 횟수 설정:** 무한 루프를 방지하기 위해 최대 재시도 횟수를 제한한다.

```python
import time
import random

def call_llm_with_retry(prompt, max_retries=3):
    for i in range(max_retries):
        try:
            # LLM 스트리밍 호출 가상 코드
            return call_llm_api(prompt)
        except Exception as e:
            if i == max_retries - 1:
                raise e
            # 지수 백오프 적용: 2^i + 랜덤 지터
            wait_time = (2 ** i) + random.random()
            print(f"Error occurred. Retrying in {wait_time:.2f}s...")
            time.sleep(wait_time)
```

### 2.2 폴백 메커니즘 (Fallback)
주 서비스의 장애가 지속될 경우 대체 수단을 통해 서비스 연속성을 보장한다.
- **모델 폴백:** 고성능 모델(예: GPT-4)에서 오류 발생 시, 상대적으로 가볍고 빠른 모델(예: GPT-3.5)로 전환하여 응답을 시도한다.
- **정적 응답 제공:** 모든 재시도가 실패했을 때, 사용자에게 안내 메시지나 미리 정의된 기본 응답을 제공한다.

### 2.3 클라이언트 측 상태 관리
스트리밍 데이터의 유실을 방지하고 사용자 경험을 개선한다.
- **청크(Chunk) 버퍼링:** 수신된 텍스트 조각을 버퍼에 저장하여 렌더링 최적화를 수행한다.
- **연결 상태 모니터링:** 하트비트(Heartbeat) 체크를 통해 연결 단절을 빠르게 감지하고 사용자에게 알림을 제공한다.

## 3. 모니터링 및 디버깅
스트리밍 오류의 빈도와 원인을 분석하기 위해 다음과 같은 지표를 추적한다.
- **에러율 측정:** 전체 요청 대비 스트리밍 중단 발생 비율을 모니터링한다.
- **지연 시간 분석:** 첫 번째 토큰 생성 시간(TTFT, Time To First Token)과 전체 생성 시간을 기록하여 타임아웃 지점을 분석한다.
- **로그 기록:** HTTP 상태 코드 및 모델의 `finish_reason`을 기록하여 네트워크 문제인지 모델 제한 문제인지 구분한다.

## 체크포인트 기반 재시도
단순한 전체 재시도는 이미 생성된 토큰을 중복 생성하게 하여 비용과 시간을 낭비한다. 이를 방지하기 위해 중단된 지점의 인덱스나 토큰 ID를 기록하는 '체크포인트 기반 재시도'를 적용한다.

**API 요청 예시 (Pseudo-code):**
클라이언트는 마지막으로 수신한 토큰의 시퀀스 번호나 텍스트 일부를 `resume_from` 파라미터로 전달하여 서버가 해당 지점부터 생성을 재개하도록 요청한다.

```json
// 1차 요청 중 50번째 토큰에서 연결 단절 발생
// 2차 재시도 요청 (체크포인트 포함)
POST /v1/chat/completions
{
  "model": "gpt-4-turbo",
  "messages": [
    {"role": "user", "content": "신뢰성 강화 방안에 대해 설명해줘."}
  ],
  "stream": true,
  "resume_from": {
    "last_token_index": 50,
    "last_content_snapshot": "...이러한 전략을 통해 시스템의" 
  }
}
```

## 네트워크 복구 및 무결성 검증
네트워크 단절 시 자동 재연결(Auto-reconnect) 로직을 구현하고, 수신 데이터의 순서와 누락 여부를 검증하기 위해 시퀀스 번호를 관리한다.

- **자동 재연결:** WebSocket이나 SSE 연결이 끊어지면 지수 백오프 알고리즘에 따라 연결을 재시도하며, 재연결 성공 시 마지막 체크포인트부터 데이터를 요청한다.
- **시퀀스 번호 관리:** 서버가 각 청크(Chunk)에 순차적인 번호(`seq_id`)를 부여하여 전송한다. 클라이언트는 수신된 `seq_id`를 확인하여 중간에 누락된 패킷이 있는지 검증하고, 누락 발견 시 해당 구간의 재전송을 요청한다.

## 스트림 완료율 및 알림 체계
단순 에러율 외에 스트리밍의 특성을 반영한 '성공적인 스트림 완료율(Stream Completion Rate)'을 핵심 지표로 관리한다.

**1. 스트림 완료율 계산 공식**
$$\text{Stream Completion Rate} = \left( \frac{\text{정상적으로 finish\_reason이 전달된 요청 수}}{\text{전체 스트리밍 시작 요청 수}} \right) \times 100$$

**2. 임계치 설정 기준**
- **Warning (주의):** 완료율 95% 미만. 일시적인 네트워크 불안정 또는 특정 리전의 지연 가능성이 있으므로 모니터링 강화.
- **Critical (심각):** 완료율 90% 미만. 서버 리소스 고갈, API 게이트웨이 설정 오류 또는 모델 인프라 장애로 판단하여 즉시 엔지니어 알림(PagerDuty, Slack 등) 발송.

## 신뢰성 강화를 위한 아키텍처 최적화
시스템 전반의 가용성을 높이기 위해 트래픽 제어 및 장애 전파 방지 패턴을 도입한다.

- **로드 밸런싱:** L7 로드 밸런서를 통해 여러 모델 서버 인스턴스로 트래픽을 분산하고, 헬스 체크(Health Check)를 통해 비정상 인스턴스를 자동으로 제외한다.
- **서킷 브레이커(Circuit Breaker):** 특정 모델 서버의 에러율이 임계치를 넘으면 호출을 즉시 차단하여 시스템 전체의 연쇄 장애(Cascading Failure)를 방지한다.

**서킷 브레이커 동작 시퀀스:**
```mermaid
sequenceDiagram
    participant Client
    participant CircuitBreaker
    participant LLM_Server

    Client->>CircuitBreaker: 요청 전송
    Note over CircuitBreaker: 상태 확인 (Closed/Open/Half-Open)
    
    alt 상태 == Closed (정상)
        CircuitBreaker->>LLM_Server: 요청 전달
        LLM_Server-->>CircuitBreaker: 응답 (성공/실패)
        CircuitBreaker-->>Client: 결과 반환
    else 상태 == Open (장애)
        CircuitBreaker-->>Client: 즉시 에러 반환 (Fallback 응답)
    end
    
    Note over CircuitBreaker: 실패 횟수 누적 시 Open 상태로 전환
    Note over CircuitBreaker: 일정 시간 후 Half-Open 상태로 전환하여 테스트 요청 전송
```

- **큐잉 시스템:** 급격한 트래픽 증가(Burst) 시 요청을 메시지 큐(Kafka, RabbitMQ 등)에 적재하여 서버가 처리 가능한 속도로 소비하게 함으로써 서버 다운을 방지한다.

## 사용자 경험(UX) 관점의 신뢰성 보완
기술적 해결책 외에 사용자가 느끼는 심리적 불안감을 줄이기 위한 인터페이스 전략을 적용한다.

- **부분적 응답 표시(Partial Rendering):** 스트리밍 중 연결이 끊기더라도 이미 수신된 텍스트는 그대로 유지하고, 중단된 지점에 "연결이 불안정합니다"라는 안내 문구와 함께 재시도 버튼을 표시한다.
- **이어쓰기(Continue Generation) 기능:** 모델의 토큰 제한이나 네트워크 문제로 응답이 끊겼을 때, 사용자가 "계속해서 작성해줘" 버튼을 누르면 이전 컨텍스트를 포함하여 다시 요청을 보내는 기능을 제공한다.
- **낙관적 UI 업데이트:** 재연결 시도 중에는 로딩 애니메이션이나 스켈레톤 UI를 통해 시스템이 복구 중임을 시각적으로 전달하여 이탈률을 낮춘다.